feat(matrix): support (array), (string) and (bool) casts via engine handlers - #17

Closes #9.

What this does

Matrix implements ObjectCastInterface::__cast() and ObjectGetPropertiesForInterface::__getFields(), dispatched by the engine's cast_object / get_properties_for handlers:

• (string) $matrix → pretty-printed rows, one per line: [1, 2, 3]
• (bool) $matrix → true (a valid matrix is never empty by construction)
• (array) $matrix → toArray() — array casts arrive at get_properties_for with the ArrayCast purpose, not at cast_object (the CastType::Array branch in __cast stays for engine paths that pass IS_ARRAY directly)
• numeric casts fall through to the engine default: warning Object of class ... could not be converted to int/float plus the substitute value 1 / 1.0, exactly as with no handler installed
• every other get_properties_for purpose (debug, serialize, var_export, JSON) reproduces the default property table via get_mangled_object_vars(), so var_dump() / serialize() / var_export() / json_encode() output is byte-identical to before (covered by tests)
• GET_OBJECT_VARS purpose serves the publicly visible entries only — the engine skips visibility filtering entirely once a custom handler is installed, so without this get_object_vars($m) would leak the mangled private table. Known deviation: class-scoped callers (a closure bound to Matrix) also get the public view, since the calling scope is not recoverable inside the FFI callback; documented and pinned by its own .phpt.

Neither hook ever throws — they run inside FFI callbacks, where PHP escalates any exception into a fatal engine error.

All dispatch is on z-engine's named CastType / PropertyPurpose enums (getCastTypeEnum() / getPurposeEnum()), not numeric constants — the values are guarded upstream against the generated engine ground truth and adapt per z-engine line, which is what lets the same code run on 8.4 and 8.5.

Upstream work this PR surfaced (both merged)

Implementing this uncovered two z-engine bugs, fixed on the 8.4 branch and merged up to master:

• fix(reflection): correct _IS_BOOL/_IS_NUMBER for PHP 8.1+ and add named cast-type enums z-engine#155 — ReflectionValue::_IS_BOOL/_IS_NUMBER predated PHP 8.1's IS_NEVER insertion, so boolean casts (engine id 18) misrouted into _IS_NUMBER branches. The fix also added the CastType / PropertyPurpose enums this PR dispatches on.
• fix(core): make CastObjectHook fall through to default engine behaviour safely z-engine#156 — CastObjectHook could not fall through safely: getResult() after a failed proceed() read the uninitialized retval slot and corrupted VM frames, and the trampoline's unconditional SUCCESS made the engine's default warning+substitute behaviour unreachable. With the fix, __cast's fall-through is the naive proceed(); return getResult(); and behaves exactly like an uninstalled handler.

Earlier revisions of this branch carried local workarounds for both (hand-declared ENGINE_IS_BOOL/PROP_PURPOSE_* constants, a hand-rolled substitute-value fallback); the final revision drops them for the upstream API.

Rebased onto multi-version master

Per review feedback, the branch is rebased onto the php: ^8.4 + z-engine: 8.4.x-dev || 8.5.x-dev master — no tag dependency. Verified with fresh installs on both minors:

• PHP 8.4.19 (z-engine 8.4.x-dev): 19/19 tests, PHPStan level max clean, PER-CS2.0 clean
• PHP 8.5.9 (z-engine dev-master): 19/19 tests, PHPStan level max clean

Tests

Seven new .phpt files (all with the mandatory three-line --INI-- section): array/string/bool casts, the numeric fall-through (asserting the restored engine warning via --EXPECTREGEX--), plus regression locks for var_dump() output and get_object_vars() visibility (outside and class-scoped).

🤖 Generated with Claude Code

https://claude.ai/code/session_01JsbdqisRfGuujN3QD9n8En